Plugins

Products built on the IntelliJ Platform are extensible applications, with the platform being responsible for creating Extensions. The IntelliJ Platform fully supports plugins (Developing a Plugin), and JetBrains hosts the JetBrains Marketplace (https://plugins.jetbrains.com), which can be used to distribute plugins that support one or more of the products. It is also possible to distribute plugins using a Custom Plugin Repository.

Plugins can extend the platform in many ways, from adding a simple menu item to adding support for a complete language, build system, and debugger. Many of the existing IntelliJ Platform features are implemented as plugins that can be included or excluded depending on the needs of the end product. See the Quick Start Guide for more details.

Plugin Alternatives

In some cases, implementing an actual IntelliJ Platform plugin might not be necessary, as alternative solutions (Alternatives to Implementing a Plugin) exist.

Open Source

The IntelliJ Platform is Open Source, under the Apache License (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/LICENSE.txt), and hosted on GitHub (https://github.com/JetBrains/intellij-community).

While this guide refers to the IntelliJ Platform as a separate entity, there is no "IntelliJ Platform" GitHub repository. Instead, the platform is considered to be an almost complete overlap with the IntelliJ IDEA Community Edition (IntelliJ IDEA Plugin Development), which is a free and Open Source version of IntelliJ IDEA Ultimate (the GitHub repository linked above is the JetBrains/intellij-community (https://github.com/JetBrains/intellij-community) repository). Please note: starting with the 2021.1 release, some plugins bundled with IntelliJ IDEA Community Edition are not open-source.

The version of the IntelliJ Platform is defined by the version of the corresponding IntelliJ IDEA Community Edition release. For example, to build a plugin against IntelliJ IDEA (2019.1.1), build #191.6707.61 means specifying the same build number tag to get the correct IntelliJ Platform files from the intellij-community repository. See the Build Number Ranges page for more information about build numbers corresponding to version numbering.

Typically, an IDE that is based on the IntelliJ Platform will include the intellij-community repository as a Git submodule and provide configuration to describe which plugins from the intellij-community, and which custom plugins will make up the product.

IDEs Based on the IntelliJ Platform

The IntelliJ Platform underlies many JetBrains IDEs. IntelliJ IDEA Ultimate (IntelliJ IDEA Ultimate) is a superset of the IntelliJ IDEA Community Edition but includes closed-source plugins (see this feature comparison (https://www.jetbrains.com/idea/features/editions_comparison_matrix.html)). Similarly, other products such as WebStorm (WebStorm Plugin Development) and DataGrip (DataGrip Plugin Development) are based on the IntelliJ IDEA Community Edition, but with a different set of plugins included and excluding other default plugins. This allows plugins to target multiple products, as each product will include base functionality and a selection of plugins from the IntelliJ IDEA Community Edition repository.

Qualifying Open Source projects can apply for free licenses (https://www.jetbrains.com/community/opensource/) of JetBrains products.

The following IDEs are based on the IntelliJ Platform:

• JetBrains (https://www.jetbrains.com) IDEs:

  • AppCode (AppCode Plugin Development)

  • CLion (CLion Plugin Development)

  • DataGrip (DataGrip Plugin Development)

  • GoLand (GoLand Plugin Development)

  • IntelliJ IDEA (IntelliJ IDEA Plugin Development)

  • MPS (https://www.jetbrains.com/mps/)

  • PhpStorm (PhpStorm Plugin Development)

  • PyCharm (PyCharm Plugin Development)

  • Rider

  • RubyMine (RubyMine Plugin Development)

  • WebStorm (WebStorm Plugin Development)

• Android Studio (Android Studio Plugin Development) IDE from Google

• Comma (https://commaide.com/) IDE for Raku (formerly known as Perl 6)

• Jmix Studio (https://www.jmix.io/tools/)

Participate in the Community

Help Others Learn

Contribute Code

Following the Latest Source Code

If you submit patches, we strongly recommend building your patches against the latest version of the code from the intellij-community Git repository ("Open Source" in "The IntelliJ Platform"). The easiest way to do so is to clone the repository, track your work in Git, and provide your changes as described in "Submit a Patch" in "Contributing to the IntelliJ Platform".

General Architectural Principles

Please do your best to follow common Java architectural principles. "Effective Java" by Joshua Bloch is the right place to start.

Tests

Functional tests cover most of the existing functionality of IntelliJ IDEA. If tests cover the area you're modifying, you must run the tests and make sure that your changes do not introduce any new test failures. It's also strongly recommended that you provide new functional tests that cover the bugs you fix or the new features that you add.

Code Formatting

We're generally pretty lax about code formatting, but at least the following conventions must be observed:

• 2 space indents in source files

• Use my prefix for instance variables and our prefix for class variables.

• New source code files must include a copyright statement with the Apache 2 license and the name of the contributor.

The easiest way to follow our code formatting guidelines is to reformat your code submissions using the shared code style, which is included in the IntelliJ IDEA Community Edition project directory.

Inspections

The IntelliJ IDEA Community Edition project includes a shared inspection profile. We strongly recommend making sure that the code you submit does not contain any warnings highlighted by the inspections configured in that inspection profile.

Javadoc Comments

If your code adds new OpenAPI interfaces, classes, methods, or extension points, you must provide Javadoc comments describing the parameters and intended usage of the APIs. Providing Javadoc or other comments for other parts of the code is a good idea but isn't required.

Commits

To avoid unnecessary work when reviewing your changes, please follow these guidelines:

• Look through all of your changes in your patch or pull request before you submit it to us. Make sure that everything you've changed is there for a reason.

• Please don't include unfinished work in the patch. Make sure that it doesn't contain any TODO comments. If you added some code and ended up not needing it, please make sure that you delete it before you submit your patch.

• Please don't include any changes that affect formatting, fixing "yellow code" (warnings), or code style along with actual changes that fix a bug or implement a feature. No one likes to leave poor code, but remember that having these changes mixed complicates the process of review.

• Please don't fix multiple problems within a single patch or pull request.

• Please don't commit your changes to configuration files (runConfigurations/IDEA.xml, codeStyleSettings.xml, misc.xml, etc.) unless it is essential for the fix itself.

• Please avoid moving or renaming code unless it is necessary for the fix. Keeping backwards compatibility is critical for the platform.

The ideal pull request would contain one commit with everything needed to fix the bug or implement a feature, but nothing else. "Commit early, commit often" perfectly applies only to local commits, but such "public commits" are hard to review (the reviewer needs either to go commit by commit spending more time to review work-in-progress, or to review all changes at once thus losing valuable information stored in commit messages).

The best would be to commit early, but then to squash all commits into one with a descriptive commit message.

Sometimes several commits for a single issue are also acceptable, but each of these should be self-contained "steps" to solve the problem.

Plugins

Describes how to create a plugin that can extend the IntelliJ Platform. Includes details on how to set up the project, register extension points, target specific versions of the IntelliJ Platform, and how to package, deploy, and test your plugins.

Base Platform

Describes the foundational layer of the architecture, which provides many features and utilities, such as the component model, the user interface, documents and editors, the virtual file system, settings, threading, and background tasks. The Base Platform layer mainly comprises the functionality of the IntelliJ Platform that does not target language features or parsing.

Project Model

Documents the Project Model, which represents the files and configuration of the currently loaded project, as well as the build system used to build the project.

PSI

The Program Structure Interface (PSI) builds the syntactic and semantic models for lots of different file types. This section describes how to work with the PSI, navigating and manipulating the syntax trees, and also looks at the powerful references system, which allows a syntax tree node to reference an item in the semantic model. It also details how PSI creates and uses indexes.

Features

Describes how to extend and interact with various features that use the PSI layer, such as code completion, navigation, AltEnter items, intentions, refactorings, and more. See also the section on Custom Languages below for language-specific features that are only applicable when adding support for a new language.

Testing

Describes the available infrastructure for writing automated tests covering the functionality of plugins.

Custom Languages

Plugins frequently extend support for existing languages, such as adding inspections to Java files. This section describes how to add support to the IntelliJ Platform for a new language that isn't supported by default, creating parsers, syntactic and semantic models, and all the features that build on top.

Product Specific

A lot of the functionalities in the IntelliJ Platform are language and product agnostic. For example, code inspections work the same in Java as they do in Ruby; it is just the syntax trees and semantic information that is different. This section describes product-specific features, such as specific project model differences and how to target them in a plugin.

Custom IDEs

Documents how to use the IntelliJ Platform to create a new, custom IDE, rather than plugins to an existing product, e.g., WebStorm, or Android Studio.

Themes

Describes how to create a theme for IntelliJ Platform-based IDEs. Includes details on how to set up the theme project, customize, build, and publish it on JetBrains Marketplace.

Resources

Links to useful resources (Useful Links), a Glossary, IntelliJ Platform Extension Point and Listener List, tips on how to Explore the IntelliJ Platform API and Learning Resources.

API and Compatibility

Information on Verifying Plugin Compatibility and list of backwards-incompatible (Incompatible Changes in IntelliJ Platform and Plugins API) API changes as well as notable changes and new features (Notable Changes and Features in IntelliJ Platform and Plugins API) in each major release of the IntelliJ Platform.

Tooling

Reference and usage guides for commonly used tools like the Gradle IntelliJ Plugin.

Essential Concepts

• Developing a Plugin.

• Testing Overview.

• Component model - the IntelliJ Platform is a component-based application and is responsible for creating components and injecting dependencies. Understanding this is necessary for building plugins.

• Extension Points (Extensions) - how to register components with extension points, and how to find out what extension points are available.

• Virtual Files - all file access should go through the Virtual File System, which abstracts and caches the file system. It means you can work with files that are on the local file system, in a zip file or are old versions from version control.

See also Glossary for a handy reference of common terms.

Code Model

The IntelliJ Platform's code model is called the PSI - the Program Structure Interface (Program Structure Interface (PSI)). The PSI parses code, builds indexes, and creates a semantic model.

Common Extension Points

The IntelliJ Platform is extremely extensible, and most features and services can be extended. Some common extension points are:

• Actions - menu and toolbar items

• Code Inspections - code analysis that looks at the syntax trees and semantic models and highlight issues in the editor.

• Intentions - context-specific actions that are available in the AltEnter menu when the text caret is at a particular location.

• Code Completion.

Creating IntelliJ Platform SDK Content

Content contributions to the IntelliJ Platform SDK are very welcome!

Before creating content for a new topic or adding large sections to the existing pages, please create an issue in the IJSDK YouTrack project (https://youtrack.jetbrains.com/newIssue?project=IJSDK&clearDraft=true&c=) to ensure we are not working on the same topic, and to agree on the form of the content draft. Checking with us before starting the work will reduce the risk of creating content that is unnecessary and won't be accepted.

Please clone the intellij-sdk-docs project from GitHub (https://github.com/JetBrains/intellij-sdk-docs), make additions or changes, and submit a pull request. Alternatively, start by clicking on the Edit page link on the top of each page.

Before creating or altering content, please consult these guides:

• SDK Docs Style Guide. This guide describes documentation conventions in terms of content style and syntax.

• SDK Code Sample Guidelines. Conventions for code sample organization, project settings, and naming conventions are described in this document.

Currently, building the site locally is not possible.

Documentation Markup

The documentation project is using Writerside (https://www.jetbrains.com/writerside), so the plugin should be installed to have full support in the IDE. The topic files themselves are Markdown (https://github.github.com/gfm/) files (*.md) using some Writerside-specific custom tags (see below).

<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->

# Contributing to the IntelliJ Platform SDK

<link-summary>Defining groups of related settings.</link-summary>

Content Style

## Task 1
### Properties
{#task1-properties}
[...]

## Task 2
### Properties
{#task2-properties}
[...]

```xml
<tagName attribute="value">XML Text</tagName>
```

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Blah     | Blah     | Blah     |

> This is a simple note.
>
{style="note"}

> This is a note.
> We have a lot of text.
> Don't make everyone read it fully by adding a good title.
>
{title="A useful title"}

![Alt text](image.png)

![Alt text](image.png){width="42"}

![Alt text](image.png){thumbnail="true"}

![Alt text](image.svg){thumbnail-same-file="true"}

Table of Contents

The table of contents for the site is displayed in the tree view on the left side of the site, and it is generated from the ijs.tree file. The list can have nested items, which are displayed as child items in the table of contents.

If absolutely required, overriding the page title text to show in table of contents is possible via toc-title attribute.

<toc-element
        id="themes_getting_started.md"
        accepts-web-file-names="themes.html,themes-intro.html"/>

Objectives

Keep the following considerations in mind while authoring an SDK code sample:

• The purpose of an SDK sample is to demonstrate an implementation pattern of the IntelliJ Platform.

• SDK code samples are instructional code, intended to teach.

  • Instructional code differs from production code in some key aspects:

    • Sacrifice some robustness in the interest of simplicity and brevity. Use error checking where it is necessary to make a point about an implementation pitfall.

    • Keep implementations as simple as possible, but use the full features of the IntelliJ Platform, programming language, and libraries.

    • Use meaningful names for interfaces, classes, fields, methods, and extension points.

    • Write instructional Javadoc comments.

  • Code samples replace lots of documentation.

• Aim for two levels of SDK samples:

  • A basic sample is focused on a particular subject by demonstrating a limited area of the IntelliJ Platform. It should show all the components and architecture but ultimately accomplish something elementary. For example, demonstrate persistence by storing only a String.

  • An advanced sample demonstrates how different parts of the IntelliJ Platform integrate and work together, such as combining inspections or intentions with non-trivial PsiTree manipulation.

Ultimately, the goal is to provide developers with roadmaps for implementing functionality in an IntelliJ Platform-based plugin. Each roadmap should contain:

• Pointers to SDK documentation about the IntelliJ Platform APIs needed to implement the functionality.

• Pointers to relevant basic SDK sample plugins.

• Pointers to related advanced SDK sample plugins.

Plugin Copyright Statements

Use the standard intellij-community copyright notice in all sample plugins authored by JetBrains:

Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.

The copyright statement must appear at the top of every source file. Use the IntelliJ Platform SDK (https://github.com/JetBrains/intellij-sdk-docs/tree/main/.idea/copyright) copyright profile.

Directory Naming Conventions for SDK Plugins

For basic samples, the plugin directory name is derived from the IntelliJ Platform extension points demonstrated. For example, foo_basics where foo corresponds to an IntelliJ Platform framework, extension point, or component. Some naming examples include facet_basics and editor_basics. There is only one basic sample per IntelliJ Platform API area.

For advanced code samples, the name should reflect the complex functionality delivered by the plugin rather than the IntelliJ Platform APIs. Advanced samples will be cross-referenced to the IntelliJ Platform APIs demonstrated in the sample.

The only symbol characters allowed in the name of a plugin root directory are underscores, such as foo_basics or max_opened_projects. However, underscores should not be used in any other symbol names, such as Artifact ID, plugin ID, package names, etc. Instead, concatenate a long name into camelCase such as maxOpenedProjects.

Group and Artifact ID

When creating a Gradle-based IntelliJ Platform plugin, the plugin's Maven coordinates (Group ID, Artifact ID, Version) are defined.

The Group ID for SDK plugins is always org.intellij.sdk.

The Artifact ID is a brief derivative of the plugin directory name. An Artifact ID should not contain symbols.

For basic code samples, it is not necessary to include "basic" in the Artifact ID. For example, the foo_basics directory name would have the Artifact ID foo.

A plugin with a longer directory name, such as conditional_operator_intention, could have the more succinct Artifact ID of conditionalOperatorIntention. (For legacy reasons, the conditional_operator_intention plugin uses a more concise Artifact ID.)

Plugin ID Conventions

The plugin ID appears between <id> ("id" in "Plugin Configuration File") elements in the plugin.xml (Plugin Configuration File) file.

In general, the plugin ID is the Group ID concatenated with the Artifact ID. For example, a plugin like facet_basics has the plugin ID org.intellij.sdk.facet.

Plugin IDs do not contain underscores.

Plugin Package Names

Packages in plugins should begin with the plugin ID. If there is only one package in a plugin, then the package name is the same as the plugin ID. Additional suffix words, separated by "." characters, can be added to form more specific package names. Package names do not contain underscores.

Plugin Directory Structure

SDK sample code should have a standard directory footprint. The standardized structure not only makes the samples simpler to navigate and understand, but it builds on the default Gradle plugin project structure.

Note that directories below the plugin root folder should not have underscore characters, and should use camelCase if needed. The following is an example directory structure for a foo_basics plugin.

code_samples/
  foo_basics/
    gradle/
    src/
      main/
        java/
          org.intellij.sdk.foo/
          icons/
            SdkIcons.java     # The standard SDK icon class
        resources/
          icons/
            sdk_16.svg        # The standard SDK icon for menus, etc.
          META-INF/
            plugin.xml        # The plugin configuration file
            pluginIcon.svg    # The standard SDK plugin icon
      test/                   # Omit if there are no tests
        java/
          org.intellij.sdk.foo/
        resources/
    build.gradle.kts
    gradlew
    gradle.bat
    settings.gradle.kts
    README.md

Gradle Build Script Conventions

SDK code samples must be developed using Gradle (Creating a Plugin Gradle Project). As of this writing, the use of Gradle in SDK code samples still relies heavily on the plugin.xml for specifying the plugin configuration. At a later, second phase, the SDK code samples will transition to rely more on the Gradle configuration.

The default contents of a Gradle build script file are produced by the New Project Wizard ("Create IDE Plugin" in "Creating a Plugin Gradle Project"). A consistent structure for an SDK code sample's Gradle build script file is essential for clarity and is based on the default produced by the project wizard. Comments in SDK code sample Gradle build scripts should only draw attention to the parts of the Gradle configuration that are unique for a plugin.

For SDK code samples, a few alterations are needed to the default build.gradle.kts file produced by the plugin wizard:

• Maintain the Gradle properties version (project.version) and group (project.group). See the Plugin Gradle Properties ("Plugin Gradle Properties and Plugin Configuration File Elements" in "Creating a Plugin Gradle Project") section for how these Gradle properties relate to the elements in plugin.xml.

• Add the following statement to the Patching DSL ("patchPluginXml" in "Gradle IntelliJ Plugin") (patchPluginXml {...}) section:

  // Patches <version> value in plugin.xml
  version.set(project.version)
  sinceBuild.set("221")
  untilBuild.set("223.*")

plugin.xml Conventions

A consistent structure for the plugin.xml configuration file (Plugin Configuration File) of an SDK code sample is important because we want to draw attention to the unique parts of the file for a plugin. Comment profusely about unique elements and configurations, and comment sparingly for the rest.

The sequence of elements in an SDK code sample plugin.xml file is:

• <id> ("id" in "Plugin Configuration File") Use the fully qualified Plugin ID.

• <name> ("name" in "Plugin Configuration File") The name value does not have to match the Plugin Directory Name. The name is used for display purposes and should reflect the functionality of the plugin. The name must start with "SDK: ".

• <version> ("version" in "Plugin Configuration File") The code sample's version in MAJOR.MINOR.FIX format.

  • MAJOR corresponds to a significant upgrade in functionality.

  • MINOR corresponds to minor refactoring and small improvements in functionality.

  • FIX corresponds to changes that fix problems without significant refactoring.

• <depends> ("depends" in "Plugin Configuration File") Include at least one dependency with the module com.intellij.modules.platform to indicate basic plugin compatibility with IntelliJ Platform-based products. Add <depends> elements containing module FQNs as needed to describe more specialized Compatibility with Multiple Products (Plugin Compatibility with IntelliJ Platform Products), and any other Plugin Dependencies (Plugin Dependencies).

• <description> ("description" in "Plugin Configuration File") is a concise explanation of what is being demonstrated and how a user would access the functionality. If the plugin by default overrides IDE behavior (such as tree_structure_provider) it must be noted in the description.

• <change-notes> ("change-notes" in "Plugin Configuration File") is an ordered list by version numbers with a brief description of changes for each version.

• <vendor> ("vendor" in "Plugin Configuration File") Set the value to IntelliJ Platform SDK. Set the attributes:

  • email omit this attribute.

  • url to the JetBrains Marketplace "https://plugins.jetbrains.com"

• The remainder of the plugin configuration elements (Plugin Configuration File) should only appear if they are needed by a specific plugin.

README File

Each code sample provided within the IntelliJ Platform SDK should contain a README file describing the sample purpose and its content. The SAMPLE_README.md (https://github.com/JetBrains/intellij-sdk-code-samples/tree/main/SAMPLE_README.md) file contains a template that should be used as an initial draft for further writing.

Each README.md file is supposed to have the same structure for better navigation and readability:

• A header with the link to the main IntelliJ SDK documentation and a page that the sample refers to.

• Quickstart section briefly describes the sample's purpose and significant parts of the IntelliJ SDK it implements.

• Extension Points section (if implements) with a listing of implemented extension points, links to the implementation classes, and names of extended classes.

• Actions section (if implements) with a listing of implemented actions, action IDs, links to the implementation classes, and names of base action classes.

• Listeners section (if implements) with a listing of implemented application- or project-level listeners, links to the implementation classes, and names of base listener classes.

• Each link that appears in the documentation has to be listed on the very bottom of the file with the clear link ID and proper prefix depending on the link context (docs:, file:, etc.).

Testing

IntelliJ Platform SDK code samples should be built and tested against the since-build version.

Code samples should build cleanly, with no warnings or errors, and new code samples should pass all default IntelliJ IDEA code inspections.

Testers should complete the following checklist. Here the term "IDE" means the IntelliJ Platform-based IDE in which the plugin is designed to run:

• The plugin should load in the IDE.

• The correct information about the plugin should display in the Settings | Plugins panel.

• If applicable, the plugin UI, such as tool windows, menu additions, etc. should display correctly.

• The functionality of the plugin should be tested with a sample file.

• If applicable, the plugin should pass unit tests.

Using Gradle

All sample plugins are based on Gradle, see Creating a Plugin Gradle Project to get started.

Additionally, the Working with Gradle in IntelliJ IDEA (https://youtu.be/6V6G3RyxEMk) screencast offers a thorough introduction to Gradle functionality inside IntelliJ IDEA.

Setting up Code Samples

Make sure plugins Git, Gradle, and Plugin DevKit are enabled.

Plugin DevKit plugin is bundled with IntelliJ IDEA until 2023.2.

Plugin DevKit Availability

When using IntelliJ IDEA 2023.3 or later, the Plugin DevKit plugin must be installed from JetBrains Marketplace (Plugin Homepage (https://plugins.jetbrains.com/plugin/22851-plugin-devkit)) as it is no longer bundled with the IDE.

Clone the intellij-sdk-code-samples (https://github.com/JetBrains/intellij-sdk-code-samples) GitHub repository via Git | Clone.... After successful cloning, the IDE suggests opening the project.

Select the code sample(s) to import via the Gradle tool window (https://www.jetbrains.com/help/idea/gradle.html#link_gradle_project).

Alternatively, import all code samples available by choosing _gradleCompositeBuild, which links all Gradle projects in a Composite Build.

After successful import, the project appears in the Gradle tool window tree as a new node.

Assign a Java 17 SDK in Settings | Build, Execution, Deployment | Build Tools | Gradle for Gradle JVM.

Invoke Reload All Gradle Projects from the Gradle tool window toolbar if necessary.

Running Code Samples

Run the plugin by using the Gradle runIde ("Executing the Plugin" in "Creating a Plugin Gradle Project") task shown under the corresponding project's Tasks node in the Gradle tool window.

获取帮助

文档不全？或者开发插件的时候被问题卡住了？请阅读下面各种情况下获得支持的所有方式。

请在所有的交流中使用英语。

Problems with the Guide

If you're having problems with the guide itself, such as missing, incorrect, or confusing content, please raise an issue on YouTrack (https://youtrack.jetbrains.com/newIssue?project=IJSDK&clearDraft=true&c=). If the problem is easily solved, you can also submit a Pull Request (Contributing to the IntelliJ Platform SDK).

If you want to report (smaller) issues for a specific page, you can also use Was this page helpful feedback form on the bottom of each page by providing more details after clicking the No button. Please try to be as specific as possible and provide your e-mail address for further questions and getting notified of updates.

If you just want to share feedback on the guide, again, raise an issue (https://youtrack.jetbrains.com/newIssue?project=IJSDK&clearDraft=true&c=), even if it's for a discussion, ideas on improvements or suggestions.

Please don't use the IJSDK YouTrack project for plugin or product support requests - it's intended for the SDK and the documentation, and you'll get a better response using one of the methods below.

本指南的问题

如果你在使用本指南的时候遇到问题，例如内容缺失，错误或者内容混乱，请在 YouTrack上提交问题 (https://youtrack.jetbrains.com/newIssue?project=IJSDK&clearDraft=true&c=) 。如果问题很容易得到解决，你也可以提交 拉取请求 (Contributing to the IntelliJ Platform SDK)。

如果你想报告特定页面的（小）问题，你还可以使用每个页面底部的 Was this page helpful 反馈表，方法是点击No按钮后提供更多详细信息。请尽量具体的描述您的问题并提供您的电子邮件地址，以便于后续问题沟通并在更新时获取通知。

如果你只是想对本指南提供反馈，同样也是通过提交问题 (https://youtrack.jetbrains.com/newIssue?project=IJSDK&clearDraft=true&c=)来进行，即便只是为了讨论，提出改进的想法或建议。

请不要使用 IJSDK YouTrack 项目来发起插件开发或者产品支持请求 — 这个项目的本意是关于SDK和文档的。如果使用下列方式之一，你会更好的得到响应。

Problems with Code - Support Issues

Please see Plugin Development FAQ (Plugin Development FAQ) and Explore the IntelliJ Platform API (Explore the IntelliJ Platform API) for tips & tricks.

For questions and problems related to plugin development itself (rather than the content of this guide), you have several options:

• #intellij-platform on JetBrains Platform Slack (https://plugins.jetbrains.com/slack/) - this chat room is a great place to ask questions about extending JetBrains products, with answers coming from both JetBrains team members and members of the community

• Plugin Development Forum (https://intellij-support.jetbrains.com/hc/en-us/community/topics/200366979-IntelliJ-IDEA-Open-API-and-Plugin-Development) - post a message to the support forum. It is regularly updated with answers by JetBrains team members.

Of course, all raised questions will be used to try and improve this guide.

代码方面的问题-支持问题

请参考 插件开发常见问题问答 (Plugin Development FAQ) 和 探索 IntelliJ Platform API (Explore the IntelliJ Platform API) 来获取相关技巧和窍门。 对于与插件开发本身有关的问题和难题（和本指南内容无关），你有几个选择： JetBrains Platform Slack上的#intellij-platform — 这个聊天室是讨论有关扩展JetBrains产品问题的好地方，解答来自JetBrains团队成员和社区成员。

插件开发论坛 (https://intellij-support.jetbrains.com/hc/en-us/community/topics/200366979-IntelliJ-IDEA-Open-API-and-Plugin-Development) - 在支持论坛上发布消息。JetBrains团队成员会定期更新并解答问题。 当然，所有收到的问题都将用于尝试和改进本指南。

Problems with Products

If you have a problem with an IntelliJ Platform-based product, such as IntelliJ IDEA, WebStorm, Rider, etc., please use any of the regular Product Support (https://www.jetbrains.com/support/) channels.

产品问题

如果在使用基于 IntelliJ 平台的产品（例如 IntelliJ IDEA、WebStorm、Rider 等）时遇到问题，请使用任何常规产品支持 (https://www.jetbrains.com/support/)渠道。

2024

2023

2022

2021

2020

2019

Structural Search and Replace Inspections

The Structural Search and Replace (SSR) (https://www.jetbrains.com/help/idea/structural-search-and-replace.html) functionality allows defining search patterns which are based not only on textual information but also on the structure of the searched code fragments, no matter how it is formatted or commented. The SSR templates can be used for creating custom inspections (https://www.jetbrains.com/help/idea/creating-custom-inspections.html), which can be an alternative for programmatic code inspections (Code Inspections). Depending on requirements, an inspection can report an issue for a code fragment matching a given template, but also provide a quick fix replacing the reported fragment with the configured replacement template. All inspection metadata like name, problem tooltip, and description are configurable. A single inspection can use multiple search and replacement templates.

Once SSR inspections are created and configured, they can be shared with other team members via inspection profiles (https://www.jetbrains.com/help/idea/customizing-profiles.html).

SSR inspections can be created only for languages providing SSR support. To verify if a given language supports SSR, invoke the Edit | Find | Search Structurally... action in an IDE supporting the language, and check if it is present in the Language select list.

See the I(J)nspector (https://ijnspector.wordpress.com/) blog for practical SSR templates examples.

IDE Scripting Console

The IDE scripting console (https://www.jetbrains.com/help/idea/ide-scripting-console.html) can be used for automating IDE's features and extracting required information, e.g., about a current project. Scripts can access the IntelliJ Platform APIs and can be implemented in Kotlin, JavaScript, or Groovy by default, but it is also possible to use other languages compliant with the JCR-223 specification (https://www.jcp.org/en/jsr/detail?id=223).

Created scripts are stored in the IDE configuration directory (https://www.jetbrains.com/help/idea/directories-used-by-the-ide-to-store-settings-caches-plugins-and-logs.html#config-directory) and can't be shared as part of project files or configuration.

Flora Plugin

The Flora (https://plugins.jetbrains.com/plugin/17669-flora-beta-) plugin allows for developing project-specific extensions as Kotlin Script (*.kts) or JavaScript (*.js) files. Flora extensions have access to all available IntelliJ Platform APIs, just like a regular plugin.

Every extension is represented by a single file and stored directly in a project's .plugins directory. Extensions can be easily shared with other team members by adding the .plugins directory to VCS. Also, adding the Flora plugin in the Settings | Build, Execution, Deployment | Required Plugins and sharing this configuration as part of a project makes it effortless to deliver additional IDE functionalities to your team without any manual setup.

Please note that the Flora plugin is in an experimental state.

LivePlugin

The LivePlugin (https://plugins.jetbrains.com/plugin/7282-liveplugin) allows for extending IntelliJ-based IDEs functionalities at the runtime, without the need of restarting IDE. It adds a new Plugins tool window that lists all available extensions and allows managing them. Extensions can be implemented in Kotlin or Groovy and edited directly in the IDE. Extensions can use all IntelliJ Platform APIs and additional LivePlugin API that shorten common use cases.

Created extensions are stored on the IDE level and can be shared with other team members as plain files, GitHub gists, or repositories. Additionally, if they are stored in a project's .live-plugins directory and LivePlugin's Run Project Specific Plugins option is enabled, all extensions from this directory will be loaded automatically when the project is opened and unloaded when the project is closed.

See the LivePlugin description (https://dmitrykandalov.com/liveplugin), presentation (https://www.youtube.com/watch?v=GcYa4lMRta0), and extensions examples (https://github.com/dkandalov/live-plugin#more-examples) for more information.

PhpStorm Advanced Metadata

PhpStorm (https://www.jetbrains.com/phpstorm/) supports special metadata files (https://www.jetbrains.com/help/phpstorm/ide-advanced-metadata.html) describing the behavior of methods and functions. This information is used for using the existing IDE features such as code completion, navigation, finding usages, and others. The metadata files can be part of project files (https://www.jetbrains.com/help/phpstorm/ide-advanced-metadata.html#create-metadata-files-inside-your-project), which makes it easy to share it between team members via version control.

Custom Language Support

Custom language support provides basic functionality for working with a particular programming language, that includes:

• File type recognition

• Lexical analysis

• Syntax highlighting

• Formatting

• Code insight and code completion

• Inspections and quick fixes

• Intention actions

Plugins can also augment existing (bundled) custom languages, e.g., by providing additional inspections, intentions, or any other features.

Refer to the Custom Language Support Tutorial (Custom Language Support Tutorial) to learn more about the topic.

Framework Integration

Framework integration consists of improved code insight features, which are typical for a given framework, as well as the option to use framework-specific functionality directly from the IDE. Sometimes it also includes language support elements for a custom syntax or DSL.

• Specific code insight

• Direct access to framework-specific functionality

Refer to the IntelliJ-HCL (https://github.com/JetBrains/intellij-plugins/tree/idea/241.14494.240/terraform) as an example of framework integration. More reference plugins can be found on JetBrains Marketplace (https://plugins.jetbrains.com/search?orderBy=update%20date&shouldHaveSource=true&tags=Framework).

Tool Integration

Tool integration makes it possible to manipulate third-party tools and components directly from the IDE without switching contexts, that implies:

• Implementation of additional actions

• Related UI components

• Access to external resources

Refer to the Gerrit integration (https://plugins.jetbrains.com/plugin/7272) plugin as an example.

User Interface Add-Ons

Plugins in this category apply various changes to the standard user interface of the IDE. Some newly added components are interactive and provide new functionality, while others are limited to visual modifications only. The Foldable ProjectView (https://plugins.jetbrains.com/plugin/17288-foldable-projectview) plugin may serve as an example.

Themes

Themes (Getting Started) give designers the ability to customize the appearance of built-in IDE UI elements.

Gradle IntelliJ Plugin

The recommended solution for building IntelliJ Platform plugins is Gradle IntelliJ Plugin.

The IntelliJ IDEA Ultimate and Community editions provide the necessary plugins to support Gradle-based plugin development: Gradle and Plugin DevKit. To verify these plugins are installed and enabled, see the help section about Managing Plugins (https://www.jetbrains.com/help/idea/managing-plugins.html).

Plugin DevKit plugin is bundled with IntelliJ IDEA until 2023.2.

Plugin DevKit Availability

When using IntelliJ IDEA 2023.3 or later, the Plugin DevKit plugin must be installed from JetBrains Marketplace (Plugin Homepage (https://plugins.jetbrains.com/plugin/22851-plugin-devkit)) as it is no longer bundled with the IDE.

Gradle IntelliJ Plugin manages the dependencies of a plugin project - both the base IDE and other plugin dependencies (Plugin Dependencies). It provides tasks to run the IDE with your plugin and to package and publish ("Publishing Plugin With Gradle" in "Publishing a Plugin") your plugin to the JetBrains Marketplace (https://plugins.jetbrains.com). To make sure that a plugin is not affected by API changes (Incompatible Changes in IntelliJ Platform and Plugins API), which may happen between major releases of the platform, you can quickly verify your plugin against other IDEs and releases.

There are two main ways of creating a new Gradle-based IntelliJ Platform plugin project:

• dedicated generator available in the New Project Wizard (https://www.jetbrains.com/help/idea/new-project-wizard.html) - it creates a minimal plugin project with all the required files

• IntelliJ Platform Plugin Template available on GitHub - in addition to the required project files, it includes configuration of the GitHub Actions CI workflows

This documentation section describes plugin structure generated with the New Project wizard, but the project generated with IntelliJ Platform Plugin Template covers all the described files and directories. See the IntelliJ Platform Plugin Template section for more information about the advantages of this approach and instructions on how to use it.

The old DevKit project model and workflow are still supported in existing projects and are recommended for creating theme plugins (Developing a Theme). See how to migrate a DevKit plugin to Gradle (Migrating DevKit Plugin to Gradle).

A dedicated SBT plugin (https://github.com/JetBrains/sbt-idea-plugin) is available for plugins implemented in Scala.

Plugin Development Workflow

• Creating a Gradle-based Plugin Project (Creating a Plugin Gradle Project)

• Configuring the Gradle IntelliJ Plugin (Configuring Gradle IntelliJ Plugin)

  • Adding Kotlin Support (Configuring Kotlin Support) (optional)

• Publishing a Plugin (Publishing a Plugin)

Creating a Plugin with New Project Wizard

plugins {
  id("java")
  id("org.jetbrains.kotlin.jvm") version "1.9.21"
  id("org.jetbrains.intellij") version "1.17.3"
}

group = "com.example"
version = "1.0-SNAPSHOT"

repositories {
  mavenCentral()
}

// Configure Gradle IntelliJ Plugin
// Read more: https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html
intellij {
  version.set("2022.2.5")
  type.set("IC") // Target IDE Platform

  plugins.set(listOf(/* Plugin Dependencies */))
}

tasks {
  // Set the JVM compatibility versions
  withType<JavaCompile> {
    sourceCompatibility = "17"
    targetCompatibility = "17"
  }
  withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
    kotlinOptions.jvmTarget = "17"
  }

  patchPluginXml {
    sinceBuild.set("222")
    untilBuild.set("232.*")
  }

  signPlugin {
    certificateChain.set(System.getenv("CERTIFICATE_CHAIN"))
    privateKey.set(System.getenv("PRIVATE_KEY"))
    password.set(System.getenv("PRIVATE_KEY_PASSWORD"))
  }

  publishPlugin {
    token.set(System.getenv("PUBLISH_TOKEN"))
  }
}

Running a Plugin With the runIde Gradle task

Gradle projects are run from the IDE's Gradle Tool window.

Keep Up To Date

Gradle IntelliJ Plugin and Gradle (https://gradle.org/install/) build system are constantly developed, and every new release brings important bug fixes, new features, and improvements that makes the development more efficient. It is strongly recommended to keep updating both Gradle and Gradle IntelliJ Plugin to the latest versions. Newer IDE releases might not be supported fully in older releases of Gradle IntelliJ Plugin.

Current Gradle IntelliJ Plugin version is 1.17.3

Target Platform and Dependencies

Which versions should your plugin support? We've collected some insights based on download statistics in Statistics: Product Versions in Use (https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html).

By default, the Gradle plugin will build a plugin project against the IntelliJ Platform defined by the latest EAP snapshot of the IntelliJ IDEA Community Edition.

If a matching version of the specified IntelliJ Platform is not available on the local machine, the Gradle plugin downloads the correct version and type. IntelliJ IDEA then indexes the build and any associated source code and JetBrains Java Runtime.

To build a plugin for more than one target platform version, see "Targeting Multiple IDE Versions" in "Build Number Ranges" for important notes.

Run IDE Task

By default, the Gradle plugin will use the same version of the IntelliJ Platform for the IDE Development Instance as was used for building the plugin. Using the corresponding JetBrains Runtime is also the default, so for this use-case no further configuration is required.

Patching the Plugin Configuration File

A plugin project's plugin.xml file has element values that are "patched" at build time from the attributes of the patchPluginXml ("patchPluginXml" in "Gradle IntelliJ Plugin") task. As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's plugin.xml file:

• If a patchPluginXml attribute default value is defined, the attribute value will be patched in plugin.xml regardless of whether the patchPluginXml task appears in the Gradle build script.

  • For example, the default values for the attributes patchPluginXml.sinceBuild ("sinceBuild" in "Gradle IntelliJ Plugin") and patchPluginXml.untilBuild ("untilBuild" in "Gradle IntelliJ Plugin") are defined based on the declared (or default) value of intellij.version ("version" in "Gradle IntelliJ Plugin"). So by default patchPluginXml.sinceBuild and patchPluginXml.untilBuild are substituted into the <idea-version> ("idea-version" in "Plugin Configuration File") element's since-build and until-build attributes in the plugin.xml file.

• If a patchPluginXml ("patchPluginXml" in "Gradle IntelliJ Plugin") task's attribute value is explicitly defined, the attribute value will be substituted in plugin.xml.

  • If both patchPluginXml.sinceBuild and patchPluginXml.untilBuild attributes are explicitly set, both are substituted in plugin.xml.

  • If one attribute is explicitly set (e.g. patchPluginXml.sinceBuild) and one is not (e.g. patchPluginXml.untilBuild has a default value), both attributes are patched at their respective (explicit and default) values.

• For no substitution of the <idea-version> element's since-build and until-build attributes, set intellij.updateSinceUntilBuild ("updateSinceUntilBuild" in "Gradle IntelliJ Plugin") to false, and do not provide patchPluginXml.sinceBuild and patchPluginXml.untilBuild values.

The best practice to avoid confusion is to replace the elements in plugin.xml that will be patched by the Gradle plugin with a comment. That way, the values for these parameters do not appear in two places in the source code. The Gradle plugin will add the necessary elements as part of the patching process. For those patchPluginXml ("patchPluginXml" in "Gradle IntelliJ Plugin") attributes that contain descriptions such as patchPluginXml.changeNotes ("changeNotes" in "Gradle IntelliJ Plugin") and patchPluginXml.pluginDescription ("pluginDescription" in "Gradle IntelliJ Plugin"), a CDATA block is not necessary when using HTML elements.

To maintain and generate an up-to-date changelog, try using Gradle Changelog Plugin (https://github.com/JetBrains/gradle-changelog-plugin).

As discussed in "Components of a Wizard-Generated Gradle IntelliJ Platform Plugin" in "Creating a Plugin Gradle Project", the Gradle properties project.version, project.group, and rootProject.name are all generated based on the input to the Wizard. However, the Gradle IntelliJ Plugin does not combine and substitute those Gradle properties for the default <id> ("id" in "Plugin Configuration File") and <name> ("name" in "Plugin Configuration File") elements in the plugin.xml file.

The best practice is to keep project.version current. By default, if you modify project.version in Gradle build script, the Gradle plugin will automatically update the <version> ("version" in "Plugin Configuration File") value in the plugin.xml file. This practice keeps all version declarations synchronized.

Verifying Plugin

The Gradle plugin provides tasks that allow for running integrity and compatibility tests:

• verifyPluginConfiguration ("verifyPluginConfiguration" in "Gradle IntelliJ Plugin") - validates the versions of SDK, target platform, APIs, etc., configured in a plugin project,

• verifyPlugin ("verifyPlugin" in "Gradle IntelliJ Plugin") - validates completeness and contents of plugin.xml descriptors as well as plugin's archive structure,

• runPluginVerifier ("runPluginVerifier" in "Gradle IntelliJ Plugin") - runs the IntelliJ Plugin Verifier (https://github.com/JetBrains/intellij-plugin-verifier) tool to check the binary compatibility with specified IntelliJ IDE builds.

Plugin Verifier integration task allows for configuring the exact IDE versions that your plugin will be checked against. See "Plugin Verifier" in "Verifying Plugin Compatibility" for more information.

Publishing Plugin

Please review the Publishing a Plugin page before using the publishPlugin ("publishPlugin" in "Gradle IntelliJ Plugin") task. That documentation explains different ways to use Gradle for plugin uploads without exposing account credentials.

Advantages of Developing a Plugin in Kotlin

Using Kotlin to write plugins for the IntelliJ Platform is very similar to writing plugins in Java. Existing Java classes can be converted to their Kotlin equivalents by using the J2K converter (https://kotlinlang.org/docs/mixing-java-kotlin-intellij.html#converting-an-existing-java-file-to-kotlin-with-j2k) (part of Kotlin plugin).

In addition to null safety (https://kotlinlang.org/docs/null-safety.html), type-safe builders (https://kotlinlang.org/docs/type-safe-builders.html), and Kotlin Coroutines, the Kotlin language offers many convenient features for plugin development, which make plugins easier to read and simpler to maintain. Much like Kotlin for Android (https://kotlinlang.org/docs/android-overview.html), the IntelliJ Platform makes extensive use of callbacks, which are straightforward to express as lambdas (https://kotlinlang.org/docs/lambdas.html) in Kotlin.

Kotlin classes can be mixed in a project with existing Java code. This might come handy when certain APIs require the use of mentioned Kotlin Coroutines.

if (logger.isDebugEnabled()) {
  logger.debug("..." + expensiveComputation());
}

inline fun Logger.debug(lazyMessage: () -> String) {
  if (isDebugEnabled) {
    debug(lazyMessage())
  }
}

logger.debug { "..." + expensiveComputation() }

Adding Kotlin Support

The IntelliJ Platform Plugin Template provides a preconfigured project using Kotlin.

IntelliJ IDEA bundles the necessary Kotlin plugin, requiring no further configuration. For detailed instructions, please refer to the Kotlin documentation (https://kotlinlang.org/docs/getting-started.html).

plugins {
  id("java")
  id("org.jetbrains.intellij") version "1.17.3"
  id("org.jetbrains.kotlin.jvm") version "1.9.23"
}

group = "org.intellij.sdk"
version = "2.0.0"

repositories {
  mavenCentral()
}

java {
  sourceCompatibility = JavaVersion.VERSION_17
}

// See https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html
intellij {
  version.set("2023.2.6")
}

tasks {
  buildSearchableOptions {
    enabled = false
  }

  patchPluginXml {
    version.set("${project.version}")
    sinceBuild.set("232")
    untilBuild.set("241.*")
  }

  compileKotlin {
    kotlinOptions.jvmTarget = "17"
  }

  compileTestKotlin {
    kotlinOptions.jvmTarget = "17"
  }
}

kotlin.stdlib.default.dependency = false

Execution failed for task ':compileKotlin'.
> Failed to transform app.jar to match attributes {artifactType=classpath-entry-snapshot, org.gradle.libraryelements=jar, org.gradle.usage=java-runtime}.
   > Execution failed for ClasspathEntrySnapshotTransform: .../lib/app.jar.
      > Java heap space

kotlin.incremental.useClasspathSnapshot=false

Plugin Implementation Notes

Kotlin Code FAQ

How to shorten references (https://intellij-support.jetbrains.com/hc/en-us/community/posts/360010025120-Add-new-parameter-into-kotlin-data-class-from-IDEA-plugin?page=1#community_comment_360002950760)

Example Plugins Implemented in Kotlin

There are many open-source Kotlin plugins (https://jb.gg/ipe?language=kotlin) built on the IntelliJ Platform. For a readily available source of up-to-date examples of plugins implemented in Kotlin, developers may look to these projects for inspiration:

• Rust (https://github.com/intellij-rust/intellij-rust)

• TeXiFy IDEA (https://github.com/Hannah-Sten/TeXiFy-IDEA)

• Deno (https://github.com/JetBrains/intellij-plugins/tree/idea/241.14494.240/Deno)

Using a JetBrains Runtime for the Development Instance

An everyday use case is to develop (build) a plugin project against a JDK, e.g., Java 17, and then run or debug the plugin in a Development Instance of the IDE. In such a situation, Development Instance must use a JetBrains Runtime (JBR) (https://www.jetbrains.com/jetbrains-runtime) rather than the JDK used to build the plugin project.

The JetBrains Runtime is an environment for running IntelliJ Platform-based IDEs on Windows, macOS, and Linux. It has some modifications by JetBrains, such as fixes for native crashes not present in official JDK builds. A version of the JetBrains Runtime is bundled with all IntelliJ Platform-based IDEs. To produce accurate results while running or debugging a plugin project in a Development Instance, follow the procedures below to ensure the Development Instance uses a JetBrains Runtime.

Enabling Auto-Reload

Starting in 2020.1, this is available for compatible dynamic plugins (Dynamic Plugins). This allows a much faster development cycle by avoiding a full restart of the development instance after detecting code changes (when JARs are modified).

Please note that any unloading problems in a production environment will ask the user to restart the IDE.

Auto-Reload does not work when the sandbox IDE instance is running under a debugger.

The Development Instance Sandbox Directory

The Sandbox Home directory contains the settings, caches, logs, and plugins for a Development Instance of the IDE. This information is stored in a different location than for the installed IDE itself (https://intellij-support.jetbrains.com/hc/en-us/articles/206544519-Directories-used-by-the-IDE-to-store-settings-caches-plugins-and-logs).

How Signing Works

To be sure a file has not been modified, the file will be signed twice – first by the plugin author, then by JetBrains Marketplace.

The plugin author's sign-verify process is as follows:

• A plugin author generates a key pair and uploads the public part to JetBrains Marketplace (this feature is not yet available).

• A build tool signs a plugin file during the assembly process.

• The user uploads the plugin file to JetBrains Marketplace.

• JetBrains Marketplace checks if the public key is present in the user profile.

• JetBrains Marketplace verifies the signature.

• The JetBrains sign-verify process is as follows:

  • JetBrains CA is used as the source of truth here.

  • Its public part will be added to the IDE Java TrustStore, while the private part will be used only once to generate an intermediate certificate.

  • The private key of JetBrains CA is super-secret; in fact, we've already said too much.

The intermediate certificate issues a certificate that will be used to sign plugins. This way, it will be possible to re-generate this certificate without access to JetBrains CA's super-secret private key. The private key of the intermediate certificate is issued and kept in the AWS Certificate Manager, and no application has access to it; people's access is also limited. So now we have an AWS-based Intermediate CA. The public part of the intermediate certificate will be added to the plugin file together with the signing certificate.

The certificate used to sign plugins is stored securely, too. JetBrains Marketplace uses AWS KMS as a signature provider to sign plugin files.

Signing Methods

To provide a suitable method for plugin signing, we have introduced the Marketplace ZIP Signer (https://github.com/JetBrains/marketplace-zip-signer) library. It can be executed using the signPlugin ("signPlugin" in "Gradle IntelliJ Plugin") task provided by the Gradle IntelliJ Plugin if your project is Gradle-based. Alternatively, a standalone CLI Tool can be used.

Both methods require a private certificate key to be already present.

openssl genpkey\
  -aes-256-cbc\
  -algorithm RSA\
  -out private_encrypted.pem\
  -pkeyopt rsa_keygen_bits:4096

openssl rsa\
  -in private_encrypted.pem\
  -out private.pem

openssl req\
  -key private.pem\
  -new\
  -x509\
  -days 365\
  -out chain.crt

signPlugin {
  certificateChain.set("""
    -----BEGIN CERTIFICATE-----
    MIIElgCCAn4CCQDo83LWYj2QSTANBgkqhkiG9w0BAQsFADANMQswCQYDVQQGEwJQ
    ...
    gdZzxCN8t1EmH8kD2Yve6YKGFCRAIIzveEg=
    -----END CERTIFICATE-----
  """.trimIndent())

  privateKey.set("""
    -----BEGIN RSA PRIVATE KEY-----
    MIIJKgIBAAKCAgEAwU8awS22Rw902BmwVDDBMlTREX440BAAVM40NW3E0lJ7YTJG
    ...
    EnNBfIVFhh6khisKqTBWSEo5iS2RYJcuZs961riCn1LARztiaXL4l17oW8t+Qw==
    -----END RSA PRIVATE KEY-----
  """.trimIndent())

  password.set("8awS22%#3(4wVDDBMlTREX")
}

publishPlugin {
  token.set("perm:a961riC....l17oW8t+Qw==")
}

signPlugin {
  certificateChain = """
    -----BEGIN CERTIFICATE-----
    MIIElgCCAn4CCQDo83LWYj2QSTANBgkqhkiG9w0BAQsFADANMQswCQYDVQQGEwJQ
    ...
    gdZzxCN8t1EmH8kD2Yve6YKGFCRAIIzveEg=
    -----END CERTIFICATE-----
  """.stripIndent()

  privateKey = """
    -----BEGIN RSA PRIVATE KEY-----
    MIIJKgIBAAKCAgEAwU8awS22Rw902BmwVDDBMlTREX440BAAVM40NW3E0lJ7YTJG
    ...
    EnNBfIVFhh6khisKqTBWSEo5iS2RYJcuZs961riCn1LARztiaXL4l17oW8t+Qw==
    -----END RSA PRIVATE KEY-----
  """.stripIndent()

  password = "8awS22%#3(4wVDDBMlTREX"
}

publishPlugin {
  token = "perm:a961riC....l17oW8t+Qw=="
}

signPlugin {
  certificateChainFile.set(file("certificate/chain.crt"))
  privateKeyFile.set(file("certificate/private.pem"))
  password.set("8awS22%#3(4wVDDBMlTREX")
}

publishPlugin {
  token.set("perm:a961riC....l17oW8t+Qw==")
}

signPlugin {
  certificateChainFile = file("certificate/chain.crt")
  privateKeyFile = file("certificate/private.pem")
  password = "8awS22%#3(4wVDDBMlTREX"
}

publishPlugin {
  token = "perm:a961riC....l17oW8t+Qw=="
}

Provide Secrets to IDE

To avoid storing hard-coded values in the project configuration, the most suitable method for local development would be using environment variables provided within the Run/Debug Configuration.

To specify secrets like PUBLISH_TOKEN and values required for the signPlugin ("signPlugin" in "Gradle IntelliJ Plugin") task, modify your Gradle configuration as follows:

Kotlin

signPlugin {
  certificateChain.set(providers.environmentVariable("CERTIFICATE_CHAIN"))
  privateKey.set(providers.environmentVariable("PRIVATE_KEY"))
  password.set(providers.environmentVariable("PRIVATE_KEY_PASSWORD"))
}

publishPlugin {
  token.set(providers.environmentVariable("PUBLISH_TOKEN"))
}

Groovy

signPlugin {
  certificateChain = providers.environmentVariable("CERTIFICATE_CHAIN")
  privateKey = providers.environmentVariable("PRIVATE_KEY")
  password = providers.environmentVariable("PRIVATE_KEY_PASSWORD")
}

publishPlugin {
  token = providers.environmentVariable("PUBLISH_TOKEN")
}

In the Run/Debug Configuration for publishPlugin ("publishPlugin" in "Gradle IntelliJ Plugin") Gradle task, provide Environment Variables using relevant environment variable names:

Note that both the private key and certificate chain are multi-line values. It is necessary to transform them first using Base64 encoding before providing the single-line field in the Environment Variables panel.

signPlugin.privateKey ("privateKey" in "Gradle IntelliJ Plugin") and signPlugin.certificateChain ("certificateChain" in "Gradle IntelliJ Plugin") properties will automatically detect and decode the Base64-encoded values.

java -jar marketplace-zip-signer-cli.jar sign\
  -in "unsigned.zip"\
  -out "signed.zip"\
  -cert-file "/path/to/chain.crt"\
  -key-file "/path/to/private.pem"\
  -key-pass "PRIVATE_KEY_PASSWORD"

Signing for Custom Repositories

Signing plugins hosted on a custom repository can be accomplished for added trust between the repository and installation. However, unlike Marketplace, the custom repository will not re-sign the plugin with the JetBrains key. Instead, a trusted private CA or self-signed certificate can be used to sign and validate plugins.

keytool -import -alias IdeaPlugin -file chain.crt -keystore pluginKeystore.jks -storepass changeit

Plugin Signature Verification

To verify the signature of a plugin, you can use the verifyPluginSignature ("verifyPluginSignature" in "Gradle IntelliJ Plugin") task.

By default, this task will use the same certificate chain as provided to the signPlugin ("signPlugin" in "Gradle IntelliJ Plugin") task in the previous section.

To verify the signature using CLI tool, execute the verify command as below:

java -jar marketplace-zip-signer-cli.jar verify\
  -in "signed.zip"\
  -cert "/path/to/chain.crt"

Uploading a Plugin to JetBrains Marketplace

Before publishing your plugin, make sure it is signed. For more details on generating a proper certificate and configuring the signing process, check the Plugin Signing (Plugin Signing) article.

Publishing Plugin With Gradle

Once you have configured Gradle support (Configuring Gradle IntelliJ Plugin), and uploaded the plugin to the plugin repository at least once, you can automatically build and deploy your plugin to the JetBrains Marketplace (https://plugins.jetbrains.com).

export ORG_GRADLE_PROJECT_intellijPublishToken='YOUR_TOKEN'

publishPlugin {
  token.set(System.getenv("ORG_GRADLE_PROJECT_intellijPublishToken"))
}

publishPlugin {
  token = System.getenv("ORG_GRADLE_PROJECT_intellijPublishToken")
}

-Dorg.gradle.project.intellijPublishToken=YOUR_TOKEN

publishPlugin {
  channels.set(listOf("beta"))
}

publishPlugin {
  channels = ['beta']
}

Plugin Without Dependencies

A plugin consisting of a single .jar file is placed in the /plugins directory.

Plugin With Dependencies

The plugin .jar file is placed in the /lib folder under the plugin's "root" folder, together with all required bundled libraries.

All jars from the /lib folder are automatically added to the classpath (see also Plugin Class Loaders (Class Loaders)).

Do Not Repackage Libraries

Do not repackage libraries into the main plugin archive (sample.jar in the sample below). Otherwise, Plugin Verifier (Verifying Plugin Compatibility) will yield false positives for unresolved classes and methods.

API Sources Location

The API source JARs must be located in the example-plugin.zip!/plugin/lib/src directory in the plugin ZIP distribution, e.g.:

The plugin distribution ZIP file can contain multiple source JARs, and there are no strict rules for the source JAR names.

Defining Plugin API

Usually, the following classes are considered as plugin API:

• Extension Point (Extension Points) and related classes

• Listener (Listeners) and related classes

• Services (Services) and utilities that provide access to the plugin data/behavior

Keep in mind that API should be stable and change very rarely as every incompatible change will break the client plugins. It is also recommended to organize the plugin code in multiple modules with clear responsibilities, e.g.:

• example-plugin-api - a module containing API

• example-plugin-impl - a module containing plugin features code that are not meant to be extended or used by client plugins

General rule to define API is to include classes that are likely to be consumed by the client plugins code.

Of course, more complex plugins may require more fine-grained structure. See Gradle IntelliJ Plugin - Usage Examples (Gradle IntelliJ Plugin – Usage Examples).

Bundling API Sources in Gradle Build Script

In the simplest case, if a project consists of a single module and plugin API is clearly isolated in a package, e.g. com.example.plugin.openapi, including the source JAR can be achieved by adding the following snippet to the tasks section of the Gradle build script:

tasks {
  val createOpenApiSourceJar by registering(Jar::class) {
    // Java sources
    from(sourceSets.main.get().java) {
      include("**/com/example/plugin/openapi/**/*.java")
    }
    // Kotlin sources
    from(kotlin.sourceSets.main.get().kotlin) {
      include("**/com/example/plugin/openapi/**/*.kt")
    }
    destinationDirectory.set(layout.buildDirectory.dir("libs"))
    archiveClassifier.set("src")
  }

  buildPlugin {
    dependsOn(createOpenApiSourceJar)
    from(createOpenApiSourceJar) { into("lib/src") }
  }
}

task createOpenApiSourceJar(type: Jar) {
  // Java sources
  from(sourceSets.main.java) {
    include '**/com/example/plugin/openapi/**/*.java'
  }
  // Kotlin sources
  from(sourceSets.main.kotlin) {
    include '**/com/example/plugin/openapi/**/*.kt'
  }
  destinationDirectory = layout.buildDirectory.dir('libs')
  archiveClassifier = 'src'
}

buildPlugin {
  dependsOn(createOpenApiSourceJar)
  from(createOpenApiSourceJar) { into 'lib/src' }
}

The above configuration will create a source JAR containing Java and Kotlin source files from the com.example.plugin.openapi package and add it to the final plugin ZIP distribution in the required example-plugin.zip!/example-plugin/lib/src directory.

If your plugin is a Gradle project and there is no clear open API package separation, it is recommended to restructure the plugin project to a Gradle multi-project variant and create a dedicated open API subproject that contains all API sources to be included in the final distribution created by the main plugin Gradle project.

Bundled Libraries

Third-Party Software and Licenses (https://www.jetbrains.com/legal/third-party-software/) lists all bundled libraries and their versions for each product.

Overriding IDE Dependencies

Gradle 7 introduced implementation scope, replacing compile scope. For this setup, to use project defined dependency instead of the bundled IDE version, add the following snippet to your Gradle build script:

configurations.all {
  resolutionStrategy.sortArtifacts(ResolutionStrategy.SortOrder.DEPENDENCY_FIRST)
}

configurations.all {
  resolutionStrategy.sortArtifacts(ResolutionStrategy.SortOrder.DEPENDENCY_FIRST)
}

Classes from Plugin Dependencies

By default, the main IDE class loader loads classes that are not found in the plugin class loader. However, in the plugin.xml (Plugin Configuration File) file, you may use the <depends> ("depends" in "Plugin Configuration File") element to specify that a plugin depends (Plugin Dependencies) on one or more other plugins. In this case, the class loaders of those plugins will be used for classes not found in the current plugin. This allows a plugin to reference classes from other plugins.

Using ServiceLoader

Some libraries use ServiceLoader (https://docs.oracle.com/javase/8/docs/api/index.html?java/util/ServiceLoader.html) to detect and load implementations. For this to work in a plugin, the context class loader must be set to the plugin's classloader and restored afterwards with the original one around initialization code:

Thread currentThread = Thread.currentThread();
ClassLoader originalClassLoader = currentThread.getContextClassLoader();
ClassLoader pluginClassLoader = this.getClass().getClassLoader();
try {
  currentThread.setContextClassLoader(pluginClassLoader);
  // code working with ServiceLoader here
} finally {
  currentThread.setContextClassLoader(originalClassLoader);
}

Exploring Available Extensions

IntelliJ Platform Extension Point and Listener List and IntelliJ Community Plugins Extension Point and Listener List list all available extension points in IntelliJ Platform and from bundled plugins in IntelliJ IDEA. Additionally, dedicated Extension Point and Listener Lists specific to IDEs are available under Product Specific. Browse usages inside existing implementations of open-source IntelliJ Platform plugins via IntelliJ Platform Explorer (https://jb.gg/ipe).

Alternatively (or when using 3rd party extension points), all available extension points for the specified namespace (defaultExtensionNs) can be listed using auto-completion inside the <extensions> ("extensions" in "Plugin Configuration File") block in plugin.xml (Plugin Configuration File). Use View | Quick Documentation in the lookup list to access more information about the extension point and implementation (if applicable). See Explore the IntelliJ Platform API for more information and strategies.

Declaring Extensions

Auto-completion, Quick Documentation, and other code insight features are available on extension point tags and attributes in plugin.xml.

To clarify this procedure, consider the following sample section of the plugin.xml file that defines two extensions designed to access the com.intellij.appStarter and com.intellij.projectTemplatesFactory extension points in the IntelliJ Platform, and one extension to access the another.plugin.myExtensionPoint extension point in another plugin another.plugin:

<!--
  Declare extensions to access extension points in the IntelliJ Platform.
  These extension points have been declared using "interface".
 -->
<extensions defaultExtensionNs="com.intellij">
  <appStarter
      implementation="com.example.MyAppStarter"/>
  <projectTemplatesFactory
      implementation="com.example.MyProjectTemplatesFactory"/>
</extensions>

<!--
  Declare extensions to access extension points in a custom plugin "another.plugin".
  The "myExtensionPoint" extension point has been declared using "beanClass"
  and exposes custom properties "key" and "implementationClass".
-->
<extensions defaultExtensionNs="another.plugin">
  <myExtensionPoint
      key="keyValue"
      implementationClass="com.example.MyExtensionPointImpl"/>
</extensions>

<extensionPoint name="myExtension" beanClass="MyExtensionBean">
  <with
      attribute="psiElementClass"
      implements="com.intellij.psi.PsiElement"/>
</extensionPoint>

Types

The IntelliJ Platform offers three types of services: application-level services (global singleton), project-level services, and module-level services. For the latter two, a separate instance of the service is created for each instance of its corresponding scope, see Project Model Introduction (Project Structure).

Avoid using module-level services as it can increase memory usage for projects with many modules.

Constructor

To improve startup performance, avoid any heavy initializations in the constructor.

Project/Module-level service constructors can have a Project (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/project/Project.java)/Module (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/module/Module.java) argument.

Do not use Constructor Injection

Using constructor injection of dependency services is deprecated (and not supported in ) for performance reasons.

Other service dependencies must be acquired only when needed in all corresponding methods, e.g., if you need a service to get some data or execute a task, retrieve the service before calling its methods. Do not retrieve services in constructors to store them in class fields.

Use inspection Plugin DevKit | Code | Non-default constructors for service and extension class to verify code.

Light Services

A service not going to be overridden/exposed as API to other plugins does not need to be registered in plugin.xml (Plugin Configuration File) (see ). Instead, annotate service class with @Service (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/components/Service.java) (see ). The service instance will be created in scope according to the caller (see ).

@Service
public final class MyAppService {
  public void doSomething(String param) {
    // ...
  }
}

@Service(Service.Level.PROJECT)
public final class MyProjectService {
  private final Project myProject;

  MyProjectService(Project project) {
    myProject = project;
  }

  public void doSomething(String param) {
    String projectName = myProject.getName();
    // ...
  }
}

@Service
class MyAppService {
  fun doSomething(param: String) {
    // ...
  }
}

@Service(Service.Level.PROJECT)
class MyProjectService(private val project: Project) {
  fun doSomething(param: String) {
    val projectName = project.name
    // ...
  }
}

Declaring a Service

To register a non-Light Service, distinct extension points are provided for each type:

• com.intellij.applicationService - application-level service

• com.intellij.projectService - project-level service

• com.intellij.moduleService - module-level service (not recommended, see Note)

To expose service API, create a separate class for serviceInterface and extend it in corresponding class registered in serviceImplementation. If serviceInterface isn't specified, it's supposed to have the same value as serviceImplementation. Use inspection Plugin DevKit | Plugin descriptor | Plugin.xml extension registration to highlight redundant serviceInterface declarations.

To provide a custom implementation for test/headless environment, specify testServiceImplementation/headlessImplementation additionally.

<extensions defaultExtensionNs="com.intellij">
  <!-- Declare the application-level service -->
  <applicationService
      serviceInterface="com.example.MyAppService"
      serviceImplementation="com.example.MyAppServiceImpl"/>

  <!-- Declare the project-level service -->
  <projectService
      serviceInterface="com.example.MyProjectService"
      serviceImplementation="com.example.MyProjectServiceImpl"/>
</extensions>

Retrieving a Service

Correct Service Retrieval

Never acquire service instances prematurely or store them in fields for later use. Instead, always obtain service instances directly and only at the location where they're needed. Failing to do so will lead to unexpected exceptions and severe consequences for the plugin's functionality.

Such problems are highlighted via inspections (2023.3):

• Plugin DevKit | Code | Application service assigned to a static final field or immutable property

• Plugin DevKit | Code | Incorrect service retrieving

• Plugin DevKit | Code | Simplifiable service retrieving

Getting a service doesn't need a read action and can be performed from any thread. If a service is requested from several threads, it will be initialized in the first thread, and other threads will be blocked until it is fully initialized.

MyAppService applicationService =
    ApplicationManager.getApplication().getService(MyAppService.class);

MyProjectService projectService =
    project.getService(MyProjectService.class);

MyAppService applicationService = MyAppService.getInstance();

MyProjectService projectService = MyProjectService.getInstance(project);

val applicationService = service<MyAppService>()

val projectService = project.service<MyProjectService>()

Sample Plugin

To clarify how to use services, consider the maxOpenProjects sample plugin available in the code samples (https://github.com/JetBrains/intellij-sdk-code-samples/tree/main/max_opened_projects).

This plugin has an application service counting the number of currently opened projects in the IDE. If this number exceeds the maximum number of simultaneously opened projects allowed by the plugin (3), it displays an information message.

See Code Samples (Code Samples) on how to set up and run the plugin.

Defining Application-Level Listeners

To define an application-level listener, add the <applicationListeners> ("applicationListeners" in "Plugin Configuration File") section to plugin.xml (Plugin Configuration File):

<idea-plugin>
  <applicationListeners>
    <listener
        class="myPlugin.MyListenerClass"
        topic="BaseListenerInterface"/>
  </applicationListeners>
</idea-plugin>

The topic attribute specifies the listener interface corresponding to the type of events to receive. Usually, this is the interface used as the type parameter of the Topic (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/extensions/src/com/intellij/util/messages/Topic.java) instance for the type of events. The class attribute specifies the class in the plugin that implements the listener interface and receives the events.

As a specific example, to receive events about all Virtual File System (Virtual File System) changes, implement the BulkFileListener interface, corresponding to the topic VirtualFileManager.VFS_CHANGES. To subscribe to this topic from code, use something like the following snippet:

messageBus.connect().subscribe(VirtualFileManager.VFS_CHANGES,
    new BulkFileListener() {
      @Override
      public void after(@NotNull List<? extends VFileEvent> events) {
        // handle the events
      }
});

To use declarative registration, it's no longer required to reference the Topic instance. Instead, refer directly to the listener interface class:

<applicationListeners>
  <listener
      class="myPlugin.MyVfsListener"
      topic="com.intellij.openapi.vfs.newvfs.BulkFileListener"/>
</applicationListeners>

Then provide the listener implementation:

package myPlugin;

final class MyVfsListener implements BulkFileListener {
  @Override
  public void after(@NotNull List<? extends VFileEvent> events) {
    // handle the events
  }
}

Defining Project-Level Listeners

Project (Project)-level listeners are registered in the same way, except that the top-level tag is <projectListeners> ("projectListeners" in "Plugin Configuration File"). They can be used to listen to project-level events, for example, tool window (Tool Windows) operations:

<idea-plugin>
  <projectListeners>
    <listener
        class="myPlugin.MyToolWindowListener"
        topic="com.intellij.openapi.wm.ex.ToolWindowManagerListener"/>
  </projectListeners>
</idea-plugin>

The class implementing the listener interface can define a one-argument constructor accepting a Project (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/project/Project.java), and it will receive the instance of the project for which the listener is created:

package myPlugin;

final class MyToolWindowListener implements ToolWindowManagerListener {
  private final Project project;

  MyToolWindowListener(Project project) {
    this.project = project;
  }

  @Override
  public void stateChanged(@NotNull ToolWindowManager toolWindowManager) {
    // handle the state change
  }
}

Additional Attributes

Registration of listeners can be restricted using the following attributes.

os

Allows restricting listener to given OS, e.g., os="windows" for Windows only (2020.1 and later)

activeInTestMode

Set to false to disable listener if Application.isUnitTestMode() (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/application/Application.java) returns true

activeInHeadlessMode

Set to false to disable listener if Application.isHeadlessEnvironment() (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/application/Application.java) returns true. Also covers activeInTestMode as test mode implies headless mode.

If declared listener topics are intended to be used by other plugins depending on your plugin, consider bundling their sources (Bundling Plugin API Sources) in the plugin distribution.

Declaring Extension Points

You can declare extensions and extension points in the plugin configuration file plugin.xml (Plugin Configuration File), within the <extensions> ("extensions" in "Plugin Configuration File") and <extensionPoints> ("extensionPoints" in "Plugin Configuration File") sections.

To declare extension points in your plugin, add an <extensionPoints> section to your plugin.xml. Then insert a child element <extensionPoint> ("extensionPoint" in "Plugin Configuration File") that defines the extension point name and the name of a bean class or an interface that is allowed to extend the plugin functionality in the name, beanClass and interface attributes, respectively.

myPlugin/META-INF/plugin.xml

<idea-plugin>
  <id>my.plugin</id>

  <extensionPoints>
    <extensionPoint
            name="myExtensionPoint1"
            beanClass="com.example.MyBeanClass"/>

    <extensionPoint
            name="myExtensionPoint2"
            interface="com.example.MyInterface"/>
  </extensionPoints>

</idea-plugin>

The name attribute assigns a unique name for this extension point. Its fully qualified name required in Using Extension Points is built by prefixing the plugin <id> ("id" in "Plugin Configuration File") as "namespace" followed by . separator: my.plugin.myExtensionPoint1 and my.plugin.myExtensionPoint2.

The beanClass attribute sets a bean class that specifies one or several properties annotated with the @Attribute (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/util/src/com/intellij/util/xmlb/annotations/Attribute.java) annotation. Note that bean classes do not follow the JavaBean standard. Implement PluginAware (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/extensions/src/com/intellij/openapi/extensions/PluginAware.java) to obtain information about the plugin providing the actual extension (see ).

Alternatively, the interface attribute sets an interface the plugin that contributes to the extension point must then implement.

The area attribute determines the scope in which the extension will be instantiated. As extensions should be stateless, it is not recommended to use non-default. Must be one of IDEA_APPLICATION for Application (default), IDEA_PROJECT for Project, or IDEA_MODULE for Module scope.

The plugin that contributes to the extension point will read those properties from the plugin.xml file.

If extension implementations are filtered according to dumb mode ("Dumb Mode" in "Indexing and PSI Stubs"), the base class should be marked with PossiblyDumbAware (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/project/PossiblyDumbAware.java) to highlight this.

Base classes for extensions requiring a key:

• LanguageExtension (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/lang/LanguageExtension.java)

• FileTypeExtension (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/fileTypes/FileTypeExtension.java)

• ClassExtension (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/util/ClassExtension.java)

• KeyedExtensionCollector (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/core-api/src/com/intellij/openapi/util/KeyedExtensionCollector.java)

See Bundling Plugin API Sources section explaining how to expose extension points sources to other plugins.

public final class MyBeanClass extends AbstractExtensionPointBean {

  @Attribute("key")
  public String key;

  @Attribute("implementationClass")
  public String implementationClass;

  public String getKey() {
    return key;
  }

  public String getClass() {
    return implementationClass;
  }

}

<idea-plugin>
  <id>another.plugin</id>

  <!-- Declare dependency on plugin defining extension point: -->
  <depends>my.plugin</depends>

  <!-- Use "my.plugin" namespace: -->
  <extensions defaultExtensionNs="my.plugin">
    <myExtensionPoint1
            key="someKey"
            implementationClass="another.some.implementation.class"/>

    <myExtensionPoint2
            implementation="another.MyInterfaceImpl"/>
  </extension>

</idea-plugin>

Using Extension Points

To refer to all registered extension instances at runtime, declare an ExtensionPointName (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/extensions/src/com/intellij/openapi/extensions/ExtensionPointName.kt) with private visibility passing in the fully qualified name matching its declaration in plugin.xml. If needed, provide a public method to query registered extensions (Sample: TestSourcesFilter.isTestSources() (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/projectModel-api/src/com/intellij/openapi/roots/TestSourcesFilter.java)).

myPlugin/src/com/myplugin/MyExtensionUsingService.java

@Service
public final class MyExtensionUsingService {

  private static final ExtensionPointName<MyBeanClass> EP_NAME =
      ExtensionPointName.create("my.plugin.myExtensionPoint1");

  public void useRegisteredExtensions() {
    for (MyBeanClass extension : EP_NAME.getExtensionList()) {
      String key = extension.getKey();
      String clazz = extension.getClass();
      // ...
    }
  }

}

A gutter icon for the ExtensionPointName declaration allows navigating to the corresponding <extensionPoint> ("extensionPoint" in "Plugin Configuration File") declaration in plugin.xml. Code insight is available for the extension point name String literal (2022.3).

Dynamic Extension Points

To support Dynamic Plugins (Dynamic Plugins) (2020.1 and later), an extension point must adhere to specific usage rules:

• extensions are enumerated on every use and extensions instances are not stored anywhere

• alternatively, an ExtensionPointListener (https://github.com/JetBrains/intellij-community/tree/idea/241.14494.240/platform/extensions/src/com/intellij/openapi/extensions/ExtensionPointListener.kt) can perform necessary updates of data structures (register via ExtensionPointName.addExtensionPointListener())

Extension points matching these conditions can then be marked as dynamic by adding dynamic="true" in their declaration:

<extensionPoints>
  <extensionPoint
          name="myDynamicExtensionPoint"
          beanClass="com.example.MyBeanClass"
          dynamic="true"/>
</extensionPoints>

All non-dynamic extension points are highlighted via Plugin DevKit | Plugin descriptor | Plugin.xml dynamic plugin verification inspection available in IntelliJ IDEA 2020.1 or later. Previous versions also highlight the dynamic attribute as "experimental".

Migration

To migrate existing code from Components to more modern APIs, please see the following guidelines.

Additional Plugin Configuration Files

A plugin can contain additional configuration files beside the main plugin.xml. They have the same format, and they are included with the config-file attribute of <depends> elements specifying plugin dependencies (Plugin Dependencies). However, some elements and attributes required in plugin.xml are ignored in additional configuration files. If the requirements differ, the documentation below will state it explicitly. One use case for additional configuration files is when a plugin provides optional features that are only available in some IDEs and require certain modules ("Modules Specific to Functionality" in "Plugin Compatibility with IntelliJ Platform Products").

Useful Resources

Please make sure to follow the guidelines from Plugin Overview page (https://plugins.jetbrains.com/docs/marketplace/plugin-overview-page.html) for an optimal presentation of your plugin on JetBrains Marketplace. The Busy Plugin Developers. Episode 2 discusses 5 tips for optimizing JetBrains Marketplace plugin page (https://youtu.be/oB1GA9JeeiY?t=52) in more detail.

See also Marketing about widgets and badges.

Configuration Structure Overview

• <idea-plugin>

  • <id>

  • <name>

  • <version>

  • <product-descriptor>

  • <idea-version>

  • <vendor>

  • <description>

  • <change-notes>

  • <depends>

  • <incompatible-with>

  • <actions>

    • <action>

      • <add-to-group>

      • <keyboard-shortcut>

      • <mouse-shortcut>

      • <override-text>

      • <synonym>

      • <abbreviation>

    • <group>

      • <action>

        • <add-to-group>

        • <keyboard-shortcut>

        • <mouse-shortcut>

        • <override-text>

        • <synonym>

        • <abbreviation>

      • <group>

      • <add-to-group>

      • <override-text>

      • <reference>

        • <add-to-group>

      • <separator>

        • <add-to-group>

    • <reference>

      • <add-to-group>

    • <separator>

      • <add-to-group>

  • <extensionPoints>

    • <extensionPoint>

      • <with>

  • <extensions>

  • <applicationListeners>

    • <listener>

  • <projectListeners>

    • <listener>

  • <resource-bundle>

Deprecated elements are omitted in the list above.

If an element or an attribute is not documented on this page, please consider them as configuration items intended to be used by JetBrains only. They should never be used by 3rd-party plugins.

idea-plugin

The plugin.xml file root element.

Required

yes

Attributes

• url (optional; ignored in additional configuration)

  The link to the plugin homepage displayed on the plugin page in the JetBrains Marketplace (https://plugins.jetbrains.com).

• require-restart (optional)

  The boolean value determining whether the plugin installation, update, or uninstallation requires the IDE restart (see Dynamic Plugins for details).

  Default value: false.

Children

• <actions>

• <applicationListeners>

• <change-notes>

• <depends>

• <incompatible-with>

• <description>

• <extensions>

• <extensionPoints>

• <id>

• <idea-version>

• <name>

• <product-descriptor>

• <projectListeners>

• <resource-bundle>

• <vendor>

• <version>

Deprecated:

• <application-components>

• <module-components>

• <project-components>